#004 New Apple Event Support in DocViewer 1.1.1 IntroductionBeginning with version 1.1.1, Apple DocViewer supports a special Apple event. This Apple event is known as the "DocViewer Lookup" event. With this event, it is possible to send a message to DocViewer requesting that it open a particular document and turn to a specific heading. This DocViewer Tech Note describes the implementation of this event. Please note that tech notes 1 - 3 do not address the Viewer portion of DocViewer and are only available to licensees of the Apple DocViewer Builder.DocViewerLookup.hAccompanying this Tech Note is a C header file for many of the constants and data structures you will need when interacting programmatically with DocViewer.Event ParametersThe Lookup event accepts three parameters. These parameters are encapsulated into a single data structure for this version. (We will parameterize them at the Apple event level for the next release.) This data structure is the only parameter of the Apple event. The structure is defined as:typedef struct { FSSpec aDoc; // FSSpec for the Doc to open/search Str255 aPattern; // String in heading to find (length // prefixed) short accessLevel;// find level }SeekParamRec, *SeekParamRecPtr, **SeekParamRecHandle;The first parameter is an FSSpec to the document you wish to open and perform the lookup in. DocViewer will open this document if it isn't already open. This document must be a DocViewer document (Creator: HLX2 Type:ONLN.) If you pass a document that does not belong to DocViewer, it will return a kWrongFileType in the 'errn' parameter of the Apple event reply. The second parameter is the heading you wish DocViewer to look for. This is a simple Pascal-style string with a maximum length of 255 characters. DocViewer uses this string as a pattern to match against the document's Table of Contents. The comparison is accomplished without regard to case or diacritical marks. (e.g. FAT == fAt, fåt = fat). If the string you pass in isn't found in the document's Table of Contents, then DocViewer will return a kEntryNotFound error.The third and final parameter is used to qualify the search pattern in the second parameter. Once DocViewer has located the entry in the Table of Contents it will confirm that the entry is in the level of the TOC hierarchy specified in the accessLevel field. DocViewer supports seven levels of hierarchy. They are defined as follows:#define kFirstLevelHier 1#define kSecondLevelHier 2#define kThirdLevelHier 3#define kFourthLevelHier 4#define kFigureLevelHier 201#define kListLevelHier 202#define kTableLevelHier 203An eighth constant has been defined that will allow the entry to be found at any level in the hierarchy. In this case, if there are duplicate entries the first entry will be chosen.#define kAnyLevelHier 999Each of these selectors is mutually exclusive, and they cannot be combined (or'd) together.Sending The EventLaunch DocViewer with DocumentThe first step when sending the lookup event is to see if DocViewer is currently running. This can be accomplished with the Process manager GetProcessInfo routine. If DocViewer is found in the list of currently running processes, you should check to see that the version of DocViewer is correct (1.1.1). This can be done using the 'vers' resource with ID #1. If DocViewer is not running, it is necessary to launch the application with the target document. If DocViewer is launched without reference to the target document, it will present its default SFGetFile dialog, and you will not be able to message the application until the dialog is dismissed. For information on launching an application with a document see "LaunchwithDoc" on the latest version of the Developer CD (Tool Chest Edition).Again, when you launch the application, it is necessary to confirm that you are launching the correct version by checking the contents of the 'vers' ID #1 resource of the DocViewer application.Send the EventOnce you have determined that DocViewer is running (or you've launched it) you can then send the event. See listing 1 for an example of sending the 'seek' event.Check for ErrorsIf DocViewer cannot find the entry requested, it will return an error in the reply of the Apple event. See listing 1 for an example of how to determine these errors.Listing 1 - Sending the 'seek' Apple event//OpenDoc// This routine takes a pointer to a SeekParamRec// and sends it to DocViewer. This routine assumes// that you've already checked to see if DocViewer is running// I removed most the error checking where it was obvious// to improve readability.OSErr OpenDoc(SeekParamRec *qData){ OSErr err = noErr; AppleEvent myEvent, reply; AEDesc myAddress; long appSig = kDocViewerAppSig; long replyError = noErr; Size actualSize; DescType gotType; err = AECreateDesc( typeApplSignature,(Ptr)&appSig, sizeof(appSig),&myAddress); err = AECreateAppleEvent(kDocViewerEventClass, kSeekEventID, &myAddress, kAutoGenerateReturnID, kAnyTransactionID, &myEvent ); err = AEPutParamPtr( &myEvent, keySeekParam, typeWildCard, (Ptr)qData, sizeof(SeekParamRec) ); err = AESend( &myEvent, &reply, kAEWaitReply, kAENormalPriority, kAEDefaultTimeout, nil, nil ); // Check to see if you got an error err = AEGetParamPtr( &reply, keyErrorNumber, typeLongInteger, &gotType, (Ptr)&replyError, sizeof(long), &actualSize); // Special case on AEDescNotFound because we'll get an error // if there is no error in the reply. if ((err != noErr) && (err != errAEDescNotFound)) { return err; } // if there's an error from DocViewer return it. // otherwise return noErr. if (replyError != noErr) return replyError; else return noErr;}à d ˇ ˇˇˇˇ d ° d WORD E
N ~ ìH å å@ ° ñ , 2hAppleGaramond Bd 2h . ˇ E E ° d ONLN dˇˇ +±Apple DocViewer † ó ° ñ ° d ONLN dˇˇ ( ÖflTechnical Note † ó ° ñ , 2gAppleGaramond Bk 2g ã` ( H Ç ã` ° d ONLN dˇˇ *' Apple Computer, Inc., Developer Press † ó ê h ä à ™ ¸¸˛ˇ¸ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ ?ˇ ˇ¯ ˇ¯ ˇ¯ ˇ¯ ˇ¯ ˇ¯ ¯ 8 ê h ä à ™ ¸¸@Ä¿ ¿ «· ¿Δ« ¿«¡ ¿ ¿ «ÅΔ¿ Δ! ¿QΔ«… ¿% ¿‡¿ˇ¸˛ˇ˙˛ % į Ä8 8 8 8 ˇ8 ¯ 8
° d ONLN d' ~3 ® *typedef ° d ONLN d"' ¥3 ‰ )6struct { ° d ONLN d,8 ¢D Δ (A ¢FSSpec ° d ONLN d38 ÿD ˆ )6aDoc; ° d ONLN d;8 D, )H// ° d ONLN d>82D¯ )!FSSpec for the Doc to open/search ° d ONLN daI ¢U Δ (R ¢Str255 ° d ONLN dhI ÿU )6 aPattern; ° d ONLN drI U, )H// ° d ONLN duI2U˛ )"String in heading to find (length ° d ONLN düT `h (] // prefixed) ° d ONLN d≠e ¢q ¿ (n ¢short ° d ONLN d¥e ÿq, )6accessLevel;// ° d ONLN d√e2qn )Z
find level ° d ONLN dœv ~Ǭ ( ~6}SeekParamRec, *SeekParamRecPtr, **SeekParamRecHandle; ° d ONLN dá ~ïÚ *AThe first parameter is an FSSpec to the document you wish to open ° d ONLN dHï ~£¸ *Cand perform the lookup in. DocViewer will open this document if it ° d ONLN då£ ~±Ù *?isn't already open. This document must be a DocViewer document ° d ONLN dñ ~ø *(Creator: HLX2 Type:ONLN.) ° d ONLN dÊÆ º! (∏ ° d ONLN dÁ±!øÓ +% If you pass a document that does not ˇp d ˇ ˇˇˇˇ d
_ , Palatino . ° d ONLN d H ~ VL +~R&belong to DocViewer, it will return a ,
Courier
° d ONLN d & IL U¶ )ŒkWrongFileType ° d ONLN d 5 H¶ VÍ )Zin the 'errn' ° d ONLN d C V ~ dD ( ` ~#parameter of the Apple event reply. ° d ONLN d i j ~ x *CThe second parameter is the heading you wish DocViewer to look for. ° d ONLN d Æ x ~ ÜË *AThis is a simple Pascal-style string with a maximum length of 255 ° d ONLN d Ü ~ îÚ *Echaracters. DocViewer uses this string as a pattern to match against ° d ONLN d6 î ~ ¢¯ *Athe document's Table of Contents. The comparison is accomplished ° d ONLN dx ¢ ~ ∞˝ *Kwithout regard to case or diacritical marks. (e.g. FAT == fAt, fåt = fat). ° d ONLN d≈ ∞ ~ æÿ *@If the string you pass in isn't found in the document's Table of ° d ONLN d æ ~ Ã] *'Contents, then DocViewer will return a
° d ONLN d- ø] À∑ )flkEntryNotFound ° d ONLN d< æ∑ Ã÷ )Zerror. ° d ONLN dC “ ~ ‡˘ ( ‹ ~FThe third and final parameter is used to qualify the search pattern in ° d ONLN dä ‡ ~ ÓÙ *Bthe second parameter. Once DocViewer has located the entry in the ° d ONLN dÕ Ó ~ ¸Û *GTable of Contents it will confirm that the entry is in the level of the ° d ONLN d ¸ ~
) * TOC hierarchy specified in the
° d ONLN d4 ˝) k )´ accessLevel ° d ONLN d? ¸k
)B field. DocViewer supports ° d ONLN d[
~¨ ( ~8seven levels of hierarchy. They are defined as follows:
° d ONLN d ° ~≠ ® *#define ° d ONLN d%° ¥≠ )6kAnyLevelHier ° d ONLN d6°2≠D )~999 ° d ONLN d:≤ ~¿‡ (º ~AEach of these selectors is mutually exclusive, and they cannot be ° d ONLN d|¿ ~Œ *combined (or'd) together. ° d ONLN dñ‹ ZÏ — (Ë ZSending The Event ° d ONLN d®Ú ~ D +$ Launch DocViewer with Document ° d ONLN d« ~ *FThe first step when sending the lookup event is to see if DocViewer is ° d ONLN d ~"÷ *=currently running. This can be accomplished with the Process ° d ONLN dL" ~0 ≤ *manager
° d ONLN dT# ≤/ )4GetProcessInfo ° d ONLN db"0¸ )T/ routine. If DocViewer is found in the list of ° d ONLN dí0 ~>˛ (: ~Ecurrently running processes, you should check to see that the version ° d ONLN dÿ> ~L· *Cof DocViewer is correct (1.1.1). This can be done using the 'vers' ° d ONLN d L ~Z Ó *resource with ID #1. ° d ONLN d2` ~n˙ *FIf DocViewer is not running, it is necessary to launch the application ° d ONLN dyn ~|– *;with the target document. If DocViewer is launched without ° d ONLN dµ| ~ä¯ *Greference to the target document, it will present its default SFGetFile ° d ONLN d˝ä ~òÛ *Edialog, and you will not be able to message the application until the ° d ONLN dCò ~¶Í *Adialog is dismissed. For information on launching an application ° d ONLN dÖ¶ ~¥Ò *@with a document see "LaunchwithDoc" on the latest version of the ° d ONLN dΔ¥ ~¬B *"Developer CD (Tool Chest Edition). ˇ> d ˇ ˇˇˇˇ d
_ , Palatino . ° d ONLN d H ~ VÌ +~RBAgain, when you launch the application, it is necessary to confirm ° d ONLN d C V ~ dˇ *Fthat you are launching the correct version by checking the contents of ° d ONLN d ä d ~ rÆ *7the 'vers' ID #1 resource of the DocViewer application. ° d ONLN d ¬ x ~ Ü ” *Send the Event ° d ONLN d — å ~ öÍ *=Once you have determined that DocViewer is running (or you've ° d ONLN d ö ~ ® *Glaunched it) you can then send the event. See listing 1 for an example ° d ONLN dW ® ~ ∂ * of sending the 'seek' event. ° d ONLN dt º ~ ÿ *Check for Errors ° d ONLN dÖ – ~ fi *HIf DocViewer cannot find the entry requested, it will return an error in ° d ONLN dŒ fi ~ ÏÛ *Ethe reply of the Apple event. See listing 1 for an example of how to ° d ONLN d Ï ~ ˙ ˇ *determine these errors. ° d ONLN d, ˇ ~ **Listing 1 - Sending the 'seek' Apple event ,
Courier
° d ONLN dW ~ ¥ * //OpenDoc ° d ONLN da ~"§ * 1// This routine takes a pointer to a SeekParamRec ° d ONLN dì! ~-∞ * 3// and sends it to DocViewer. This routine assumes ° d ONLN d«, ~8Ï * =// that you've already checked to see if DocViewer is running ° d ONLN d7 ~C‘ * 9// I removed most the error checking where it was obvious ° d ONLN d?B ~N * // to improve readability. ° d ONLN dZM ~YJ * "OSErr OpenDoc(SeekParamRec *qData) ° d ONLN d}X ~d Ñ * { ° d ONLN dÄc êo Æ + OSErr ° d ONLN dãc ·o) )Q err = noErr; ° d ONLN dôn êz à (w ê
AppleEvent ° d ONLN d•n ·z; )QmyEvent, reply; ° d ONLN d∂y êÖ ¥ (Ç êAEDesc ° d ONLN d¡y ·Ö )Q
myAddress; ° d ONLN dÕÑ êê ® (ç êlong ° d ONLN d◊Ñ ·ê} )QappSig = kDocViewerAppSig; ° d ONLN dÛè êõ ® (ò êlong ° d ONLN d˝è ·õS )QreplyError = noErr; ° d ONLN dö ê¶ ® (£ êSize ° d ONLN d ö ·¶# )Q actualSize; ° d ONLN d)• ê± ¿ (Æ êDescType ° d ONLN d5• ·± )QgotType; ° d ONLN dAª ê« (ƒ êerr = AECreateDesc( ° d ONLN dUª«» )~ typeApplSignature,(Ptr)&appSig, ° d ONLN d{Δ Ω“_ (œ Ωsizeof(appSig),&myAddress); ° d ONLN dö‹ ê˯ ( ê<err = AECreateAppleEvent(kDocViewerEventClass, kSeekEventID, ° d ONLN dÍÁ)Ûı +ô "&myAddress, kAutoGenerateReturnID, ° d ONLN d Ú)˛› * kAnyTransactionID, &myEvent ); ° d ONLN dH êÚ ( ê;err = AEPutParamPtr( &myEvent, keySeekParam, typeWildCard, ° d ONLN dí ‡ +~ #(Ptr)qData, sizeof(SeekParamRec) ); ° d ONLN d∑) ê5§ (2 ê.err = AESend( &myEvent, &reply, kAEWaitReply, ° d ONLN dÒ4 ·@ø +Q %kAENormalPriority, kAEDefaultTimeout, ° d ONLN d"? ·K# * nil, nil ); ° d ONLN d.U ~ab (^ ~& // Check to see if you got an error ° d ONLN dV` êl˛ + =err = AEGetParamPtr( &reply, keyErrorNumber, typeLongInteger, ° d ONLN d£kw∞ +~ &gotType, (Ptr)&replyError, ° d ONLN d≈v ΩÇ … ( Ω ° d ONLN dœvÇ∞ )Qsizeof(long), &actualSize); ° d ONLN dÏÅ êç¯ (ä ê<// Special case on AEDescNotFound because we'll get an error ° d ONLN d*å êòn * %// if there is no error in the reply. ° d ONLN dQó ê£∂ * 1if ((err != noErr) && (err != errAEDescNotFound)) ° d ONLN dÑ¢ êÆ ñ * { ° d ONLN dà≠ ôπ € + return err; ° d ONLN dï∏ êƒ ñ (¡ ê} ˇú d ˇ ˇˇˇˇ d
_ ,
Courier
. ° d ONLN d H ê T∞ +êQ0// if there's an error from DocViewer return it. ° d ONLN d 2 S ê _, * // otherwise return noErr. ° d ONLN d N ^ ê j * if (replyError != noErr) ° d ONLN d j i ¢ u + return replyError; ° d ONLN d ~ t ê Ä ® ( } êelse ° d ONLN d Ü ¢ ã + return noErr; ° d ONLN d î ä ~ ñ Ñ ( ì ~} ˇ
